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About AnyMail/400 Mail Server Framework Support (SC41-5411) 


This book contains information about the mail server frame- 
work (MSF) on the AS/400 system. The book is organized 
as follows: 


e Introduction to the mail server framework (Chapter 1, 
“AnyMail/400 Mail Server Framework - Introduction’). 


e Usage considerations for the mail server framework 
(Chapter 2, “Operations Considerations”). The control 
language (CL) commands used to start and end the 
framework operation are in this chapter. There is also 
information about error messages and error recovery. 


¢ Configuration considerations for the mail server frame- 
work (Chapter 3, “Configuration Considerations”). This 
chapter explains how to find the registered exit points 
and how to register exit programs with an exit point. 


¢ Description of the mail server framework structure 
(Chapter 4, “Mail Server Framework Structure”). This 
includes definitions of exit points and exit point pro- 
grams. 


¢ Conceptual information about the mail server framework 
messages (Chapter 5, “Mail Server Framework Message 
Concepts”), including MSF message lists and MSF data 
types. 


¢ Overview of mail server framework APIs (Appendix A, 
“Mail Server Framework APIs”). 


e Information about the QZMF journal, journal formats, and 
journal logging (Appendix B, “MSF Journal Logging and 
Journal Formats’). 


¢ Description of the preregistered exit point programs that 
are shipped with MSF (Appendix C, “Preregistered Exit 
Point Programs’). 


¢ Description of how SNA distribution services (SNADS) 
uses the mail server framework to route and distribute 
messages (Appendix D, “How Mail Server Framework 
Works with SNADS, Object Distribution, and 
OfficeVision’). 


The term operator refers to the system operator as the 
person responsible for operating the console, responding to 
messages, and diagnosing any system malfunctions 
(problem analysis). 


For a list of publications related to this book, see the “Bibli- 
ography.” 


Who Should Use This Book 


This book supplies the system operator and system adminis- 
trator with the information needed to use the mail server 
framework on the AS/400 system. The operator's role is to 
maintain and support mail on the AS/400 system. The oper- 
ator may find the following parts of this book most useful 
when using the framework: 


© Copyright IBM Corp. 1997 


Chapter 1, AnyMail/400 Mail Server Framework - Intro- 
duction 

Chapter 2, Operations Considerations 

Chapter 3, Configuration Considerations 

Appendix B, MSF Journal Logging and Journal Formats 
Appendix C, Preregistered Exit Point Programs 
Appendix D, How Mail Server Framework Works with 
SNADS, Object Distribution, and OfficeVision 


This book also supplies the business partner or system pro- 
grammer with conceptual information about the mail server 
framework. Use the following parts of this book to better 
understand how the mail server framework is used: 


Chapter 1, AnyMail/400 Mail Server Framework - Intro- 
duction 

Chapter 3, Configuration Considerations 

Chapter 4, Mail Server Framework Structure 

Chapter 5, Mail Server Framework Message Concepts 
Appendix A, Mail Server Framework APIs 


Benefits of Using the Mail Server 
Framework Support 


The mail server framework provides the basis for 
OfficeVision mail, SNA distribution services (SNADS), and 
any future mail offering on the AS/400 system. The QMSF 
mail server framework jobs, running in the QSYSWRK sub- 
system, support the mail server framework. 


Users of the mail server framework can tailor their mail appli- 
cations to meet their specific needs. The user applications 
are enabled and managed by the mail server framework. 


Prerequisite and Related Information 


For information about other AS/400 publications (except 
Advanced 36), see either of the following: 


e¢ The Publications Reference book, SC41-5003, in the 
AS/400 Softcopy Library. 

e¢ The AS/400 Information Directory, a unique, multimedia 
interface to a searchable database that contains 
descriptions of titles available from IBM or from selected 
other publishers. The AS/400 Information Directory is 
shipped with the OS/400 operating system at no charge. 


Information Available on the World Wide 
Web 


More AS/400 information is available on the World Wide 
Web. You can access this information from the AS/400 
home page, which is at the following uniform resource locator 
(URL) address: 


Vii 


http://www.as400.ibm.com Select the Information Desk, and you will be able to access a 
variety of AS/400 information topics from that page. 
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Chapter 1. AnyMail/400 Mail Server Framework - Introduction 


The AnyMail/400 mail server framework is an open structure 
for electronic mail distribution that is provided with the 
OS/400 operating system. AnyMail/400 functions are a set 
of mail-related functions that provide open and flexible inter- 
faces to support mail on the AS/400. The mail server frame- 
work (MSF) is the distribution framework. The primary 
function of the mail server framework is to allow the distribu- 
tion of electronic mail messages (for example, voice, video, 
or text). 


On the AS/400 system, the mail server framework performs 
the following functions: 


¢ Creates and queues MSF messages 
e Distributes MSF message information by calling config- 
ured exit programs 


An exit point is a specific point in a system function or 
program where control is passed to one or more specified 
programs. An exit point passes control to an exit program. 
The exit program can be written by the user or it can be a 
program that is already on the system. An application 
program interface (API) is a functional interface supplied by 
the operating system that allows an application program 
written in a high-level language to use specific data or func- 
tions of the operating system. 


The mail server framework allows programs to be configured 
and accessed through an API. A snap-in is a registered exit 
point program that is called from a mail server framework exit 
point. The user-written exit programs provide the mail 
message processing required for each MSF message that is 
created. 


The mail server framework (MSF) message contains informa- 
tion that defines the electronic mail message. The mail 
server framework does not process the contents of a mail 
message. Instead, it determines which exit program is 
allowed to work with the MSF message and it tracks the flow 
of the MSF message through the framework. When an MSF 
message is sent, the MSF data type is stored and used 
asynchronously. The framework also provides support for 
electronic mail messages that arrive from other systems. 


Figure 1-1 on page 1-3 illustrates client mail enabled appli- 
cations using the AS/400 system as a server and an AS/400 
application, such as OfficeVision. These applications are 
creating MSF messages and the exit point programs config- 
ured in the framework use the information in the messages 
to send the information to applications on other systems. 


Figure 1-2 on page 1-4 illustrates electronic mail information 
arriving from applications on other systems. The support for 
the information arriving from specific protocols uses the MSF 
by creating MSF messages. The framework then uses exit 
point programs to deliver the message information to a 
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system supported message store. The client and the AS/400 
application would then read the information from the 
message store. 


The MSF message might be created by an application and, 
as a result of using specific exit point programs, the informa- 
tion might be sent to other applications on the same system, 
as well as applications on other systems. Also, messages 
could be arriving from other systems. This is not shown in 
Figure 1-1 on page 1-3 or Figure 1-2 on page 1-4. Asa 
result of using specific exit point programs, that information 
could be both delivered to the application on that system and 
forwarded to another system. 


The exit points allow you to install software to affect MSF 
message flow through the mail server framework. For each 
of the mail server framework exit points provided, functions 
of the exit programs follow: 


List expansion 
Allows for expansion of the distribution lists for 
the MSF message. It expands any distribution 
list found in a recipient list. Note that distribution 
lists may contain other distribution lists that can 
be expanded further. 


Address resolution 
Allows for address mapping for each destination 
address and adds the correct information to the 
MSF message recipient information so appro- 
priate exit programs can be called at later exit 
points. 


Envelope processing 
Allows the message envelope to be changed to 
a format that the mail delivery system accepts. 


Attachment conversion 
Allows for changes or additions to MSF message 
attachments. 


Security and authority 
Allows for verification of user authority to dis- 
tribute the MSF message information to 
addresses in its recipient list, before the MSF 
message is delivered using the local or remote 
delivery exit programs. 


Local delivery 
Allows for delivery of the MSF message to local 
recipients. 


Message forwarding 
Allows forwarding of the MSF message informa- 
tion to remote recipients. 


Non-delivery 
Allows for reporting of the non-delivery of an 
MSF message. 
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Attachment management 
Allows for management of attachments refer- 
enced by an MSF message as part of the 
message distribution. 
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Accounting 
Allows for an audit trail of activity required in the 
electronic mail environment. 


See Chapter 4, “Mail Server Framework Structure” for more 
information about each of the exit points. 
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Chapter 2. Operations Considerations 


If you use applications such as OfficeVision/400 or object 
distribution, make sure that both the SNADS subsystem and 
the mail server framework are active. 


Starting and Stopping the Mail Server 
Framework 


There are two control language (CL) commands that control 
the processing of MSF messages: 


¢ Start Mail Server Framework (STRMSF) 
e¢ End Mail Server Framework (ENDMSF) 


The primary purposes of the STRMSF and ENDMSF com- 
mands are to start and end the framework, and to reset the 
framework when errors occur. 


The Start Mail Server Framework 
(STRMSF) Command 


The Start Mail Server Framework (STRMSF) command starts 
the mail server framework jobs in the system work sub- 
system (QSYSWRk). For more information about 
QSYSWRK, see the Work Management book. There are two 
parameters you can specify on the STRMSF command. 


MSGOPT (Message Option) 
This parameter specifies how the mail server framework 
processes existing MSF messages. 


*RESUME is the default option, which allows all existing 
MSF messages to continue processing from the point 
the mail server framework was previously ended. 


*RESET allows all existing MSF messages to be pro- 
cessed as if they were just created. Users may receive 
duplicate messages when this parameter is used. 


r—— Note 


*CLEAR deletes all existing MSF messages. Use 
the *CLEAR option only when a software error is 
reported with the mail server framework or its asso- 
ciated exit point programs that requires all MSF 
messages to be deleted. Use the option only when 
you want to remove all mail message traffic from the 
system because of errors. The possibility may exist 
that a message was already delivered before an 
error occurred. If this option is used, all messages 
are deleted and cannot be recovered. 


NBRMSFJOB (Number of Mail Server Framework Jobs) 
This parameter specifies the number of mail server 
framework jobs to start in the QSYSWRK subsystem. 
Several MSF messages can be processed concurrently. 
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The valid value range is 1 through 99. If mail traffic is 
high, use a larger value. Performance may be affected 
by the amount of mail traffic occurring. 


The default for this parameter is 3. 


Example 1: Starting One Mail Server Framework Job 
STRMSF NBRMSFJOB(1) 


This example starts one QMSF job (in the QSYSWRK sub- 
system) in a normal manner, processing any MSF messages 
at the point at which processing was interrupted. 


Example 2: Restarting Mail Server Framework Jobs 
STRMSF MSGOPT(*RESET) 


This example restarts the MSF jobs, using the default of 3. 
The MSF messages, partially handled by previous MSF jobs, 
are processed again as if they were just created. 


The End Mail Server Framework (ENDMSF) 
Command 


The End Mail Server Framework (ENDMSF) command ends 
the mail server framework jobs in the system work sub- 
system (QSYSWRk). This command stops all MSF 
message distribution; however, MSF messages can continue 
to be created even when the QMSF jobs are intentionally 
ended or have failed. These messages will be processed 
when the QMSF jobs are restarted by the STRMSF 
command. 


There are two parameters you can specify on the ENDMSF 
command. 


OPTION (Option) 
This parameter specifies whether the mail server frame- 
work jobs in QSYSWRK end immediately or in a con- 
trolled manner. 


*CNTRLD allows all MSF jobs to end in a controlled 
manner. This option allows each framework job a 
chance to process the MSF messages completely before 
the job ends. *CNTRLD is the default. 


*“IMMED allows all MSF jobs to end immediately. The 
MSF messages being processed when the jobs end are 
reprocessed when the mail server framework is 
restarted. 


DELAY (Delay) 
This parameter can be used to specify the maximum 
amount of delay time, in seconds, before the MSF jobs 
are ended. 


This parameter is ignored if OPTION(*IMMED) is speci- 
fied. 


Valid values range from 1 through 999999 seconds. 


The default option for this parameter is 30 seconds, 
which means that a maximum delay time of 30 seconds 
is allowed before the MSF jobs are ended. 


Example 1: Ending the Mail Server Framework in a Con- 
trolled Manner 


ENDMSF OPTION(*CNTRLD) DELAY (60) 


This example ends the MSF jobs in the QSYSWRK sub- 
system in a controlled manner. The MSF jobs have 60 
seconds to complete processing any MSF messages cur- 
rently being handled. 


Example 2: Ending the Mail Server Framework Imme- 
diately 


ENDMSF OPTION(*IMMED) 


This example ends the MSF jobs in the QSYSWRK sub- 
system immediately. The MSF jobs do not complete pro- 
cessing of any MSF messages currently being handled. 


MSF QSYSWRK Jobs 


The STRMSF command starts a specified number of jobs in 
the QSYSWRK subsystem named QMSF. 


These jobs perform the distribution function of the mail server 
framework. Note MSF messages can be created in other 
jobs. 
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Figure 2-1. QMSF Jobs in QSYSWRK Subsystem 


Managing MSF Jobs 


There is an autostart entry, QZMFECOX, that is shipped as 
part of the QSYSWRK subsystem. Whenever the 
QSYSWRK subsystem is started, one QMSF job is started 
by the autostart job entry. 


If you want to change the number of jobs that are started in 
the QSYSWRK subsystem, change the STRMSF command 
that is in the request data of the QSYS/QZMFEJBD job 
description. Use the Change Job Description (CHGJOBD) 
command to make the change. 


If you do not want any MSF jobs started when the 
QSYSWRK subsystem starts, remove the autostart job entry, 
QZMFECOX, from the QSYSWRK subsystem description. 
Use the Remove Autostart Job Entry (RMVAJE) command. 


For more information about QSYSWRK and work manage- 
ment, refer to the Work Management book. 


To work with the QMSF jobs, first locate the QOYSWRK sub- 
system where they are running. Use the Work with Sub- 
system display. Type WRKSBS on the command line and 
press the Enter key. Then type 8 in the Opt field next to 
QSYSWRK. 
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Figure 2-2. Work with Subsystems Display 


QSYSWRK contains several jobs relating to the OS/400 
operating system. You can expect to see at least one QMSF 
job running in the QSYSWRK subsystem when it is started. 


The reason for having more than one QMSF job is 
throughput performance. If you have only a very few mail 
users on your system, consider reducing the number of 
QMSF jobs. However, if the mail processing appears to be 
very slow, consider starting more QMSF jobs. 


Figure 2-3 shows QSYSWRK with QMSF and other jobs that 
typically run there. In this particular example, there are three 
QMSF jobs running. 


The MSF jobs are named QMSF. To work with a QMSF job, 
use option 5. 


i = 
Work with Subsystem Jobs RCHASEEL 
01/16/95 15:53:21 
Subsystem .......... 2  QSYSWRK 
Type options, press Enter. 
2=Change 3=Hold 4=End 5=Work wit 6=Release 7=Display message 
8=Work with spooled files 13=Disconnect 
Opt Job User Type -----Status----- Function 
__ QDIRSHDCTL = QDOC BATC ACTIVE * -DIRSHD 
5 QMSF QMSF BATC! ACTIVE 
_ MSF QMSF BATCI ACTIVE 
_ MSF QMSF BATC! ACTIVE 
___ QTCPIP QSYS BATC! ACTIVE 
__- QTFTP01045 = QTCP BATCI ACTIVE CMD-RGZPFM 
___- QTFTP01231 =QTCP BATC! ACTIVE CMD-MOVOBJ 
___ QTFTP01956 =QTCP BATC! ACTIVE CMD-MOVOBJ 
___- QTFTP10209 = QTCP BATCI ACTIVE CMD-MOVOBJ 
___- QTFTP27001 = QTCP BATCI ACTIVE CMD-RGZPFM 
More... 
Parameters or command 
=a2> 
F3=Exit F4=Prompt F5=Refresh F9=Retrieve F1l=Display schedule data 
F12=Cancel 
a =, 


Figure 2-3. Work with Subsystem Jobs Display 


Description Considerations 


Following are tips to consider when you are working with 
subsystem descriptions and job descriptions. 


Descriptions Reset During OS/400 
Installation 


When the OS/400 licensed program is installed, all sub- 
system descriptions and job descriptions get replaced. 
Therefore, if either QSYSWRK subsystem description or 
QZMFEMJBD job description is changed before an installation 
of OS/400, the changes will be lost after the installation is 
completed. If changes to the descriptions need to be saved, 
the job description and subsystem description objects should 
be saved before the installation. These objects can then be 
restored after the installation completes. Use the Save 
Object (SAVOBJ) and Restore Object (RSTOBJ) commands. 


Changing Subsystem and Job 
Descriptions 


If you change the subsystem description and job description, 
the subsystem may not start or any jobs associated with 
MSF may fail to run. 


No log entries are made to indicate there is an error. 


Error Recovery and Error Messages 


QMSF Job Error Recovery 


If MSF messages are not processed: Situations may 
occur in which you find that messages are not being pro- 
cessed. Error messages or job log messages may indicate 
that the mail server framework stopped the processing of 
some messages and is beginning to process new messages 
from the message queue. 


To recover from this situation, check the job logs for the exit 
point and the exit program running when MSF stopped pro- 
cessing the messages. Use the information to determine 
where and why MSF stopped processing the messages. 


If the mail server framework ends: |f the MSF job in 
QSYSWRK ends, first try restarting MSF. If that does not 
resolve the problem, check for messages in QSYSOPR and 
in the job logs for the QMSF jobs that are running that 
caused MSF to end. The mail server framework is finding 
something it cannot process, so it ends the framework. 


A case where this could occur is if someone deleted the exit 
point program, but did not remove it (unregister the program) 
from the exit point. You can use the Work with Registration 

Information (WRKREGINF) display to check for this situation. 
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If these messages appear in the job log: 
e¢ CPFAF95 - Job ended 


— Exit programs encountered severe errors causing 
the job to end. 

— The mail server framework encountered abnormal 
conditions. 

— Exit programs encountered situations that stopped 
the processing of MSF messages and ended the 
MSF job. 


e CPFAF98 - Message postponed 
One of the exit programs determined that an MSF 
message should be postponed until the next STRMSF. 


To recover from these messages, use the Display Job Log 


(DSPJOBLOG) command to determine what the problem is. 


Display the message and use the recovery information to 
correct the problem. Then restart MSF. 


See the Alerts Support book for a list of the IBM-supplied 
alertable messages shipped with OS/400. 
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STRMSF and ENDMSF Command Error 
Recovery 


When the STRMSF and ENDMSF commands are started: 
Sometimes you may get a message indicating that MSF is 
already active. If this error occurs, you must end the mail 
server framework (using the ENDMSF command) before the 
MSF will start again. 


What if the job log contains error message CPFAFA4: 
There are two ways to recover from the CPFAFA4 error 
message. 


e Use the Remove Mail Server Framework Configuration 
(QzmfRmvMailCfg) API. 


e Use the Work with Registration display to remove an exit 
program. See Chapter 3, “Configuration Considerations” 
for more information about using this display. 


Journal entries in the QZMF journal will help you determine 
when these errors occurred. See Appendix B, “MSF Journal 
Logging and Journal Formats” for more information about 
journal types and their descriptions. 
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This chapter explains how you can find the registered exit 
points and how to register exit programs with an exit point. 


Exit Point Program Registration 


An exit point program is registered with one of the following 
ten MSF exit points: 


QIBM_QZMFMSF_LST_EXP 
QIBM_QZMFMSF_ADR_RSL 
QIBM_QZMFMSF_ENL_PSS 
QIBM-QZMFMSF_ATT_CNV 
QIBM_QZMFMSF_SEC_AUT 
QIBM_QZMFMSF_LCL_DEL 
QIBM_QZMFMSF_MSF_FWD 
QIBM_QZMFMSF_NON_DEL 
QIBM_QZMFMSF_ATT_MGT 
QIBM_QZMFMSF_ACT 


To view the exit points, use the WRKREGINF command. 

You probably have a number of exit points registered on your 
system, but you can work with only MSF exit points by typing 
WRKREGINF FORMAT (MSFF0100) on the command line. 


Exit points are shown in alphabetical order as follows: 


Work with Registration Information 


Type options, press Enter. 
5=Display exit point 8=Work with exit programs 


Exit 
Exit Point 
Opt Point Format Registered Text 


QIBM_QZMFMSF_ACT MSFFO100 *YES MSF Accounting Exit 
QIBM_QZMFMSF_ADR_RSL MSFFO100 *YES MSF Address Resolution 
QIBM_QZMFMSF_ATT_CNV MSFFO100 *YES MSF Attachment Conversion 
QIBM_QZMFMSF_ATT_MGT MSFFO100 *YES MSF Attachment Management 
QIBM_QZMFMSF_ENL_PSS MSFFO100 *YES MSF Envelope Processing 
QIBM_QZMFMSF_LCL_DEL MSFFO100 *YES MSF Local Delivery 
QIBM_QZMFMSF_LST_EXP MSFFO100 *YES MSF List Expansion 
QIBM_QZMFMSF_MSG_FWD MSFFO100 *YES MSF Message Forwarding 
QIBM_QZMFMSF_NON_DEL MSFFO100 *YES MSF Non Delivery 
QIBM_QZMFMSF_SEC_AUT MSFFO100 *YES MSF Security and Authority 
QIBM_QZMFMSF_TRK_CHG MSFFO100 *YES MSF Track Mail Message Change 
More... 


mmand 
> 
E 


Sse) 
wie 


xit  F4=Prompt F9=Retrieve F12=Cancel 


Figure 3-1. Work with Registration Information - First Display 


© Copyright IBM Corp. 1997 


[ Work with Registration Information | 


Type options, press Enter. 
5=Display exit point 8=Work with exit programs 


Exit 
Exit Point 
Opt Point Format Registered Text 


__ QIBM_QZMFMSF_VLD_TYP MSFFO100 *YES MSF Validate Type 


Bottom 
Command 
=22> 


F3=Exit F4=Prompt F12=Cancel 


L 5 


Figure 3-2. Work with Registration Information - Second Display 


F9=Retrieve 


The first ten exit points you see here are those described in 
Chapter 4, “Mail Server Framework Structure.” 


There are two other exit points 
(QIBM_QZMFMSF_TRK_CHG and 
QIBM_QZMFMSF_VLD_TYP). These exit points can be 
called by MSF to start a program to track changes made to 
an MSF message and to validate information associated with 
an MSF message. For more information about how an MSF 
message changes, refer to “How the MSF Message 
Changes” on page 5-4. This information is useful when 
testing exit point programs. 


To display information about the specific exit point, use 
option 5. To view and work with programs registered with a 
specific exit point, use option 8. The address resolution exit 
point is displayed by typing 8 next to exit point 
QIBM_QZMFMSF_ADR_RSL in the Opt field. 


[ Work with Registration Information | 


Type options, press Enter. 


5=Display exit point 8=Work with exit programs 
Exit 
Exit Point 
Opt Point Format Registered Text 
__ QIBM_QZMFMSF_ACT MSFFO100 *YES MSF Accounting Exit 
_8  QIBM_QZMFMSF_ADR_RSL MSFFO100 *YES MSF Address Resolution 
__ QIBM_QZMFMSF_ATT_CNV MSFFO100 *YES MSF Attachment Conversion 
_ QIBM_QZMFMSF_ATT_MGT MSFFO100 *YES MSF Attachment Management 
_ QIBM_QZMFMSF_ENL_PSS MSFFO100 *YES MSF Envelope Processing 
__ QIBM_QZMFMSF_LCL_DEL MSFFO100 *YES MSF Local Delivery 
___ QIBM_QZMFMSF_LST_EXP MSFFOQ100 *YES MSF List Expansion 
__ QIBM_QZMFMSF_MSG_FWD MSFFO100 *YES MSF Message Forwarding 
___ QIBM_QZMFMSF_NON_DEL MSFFO100 *YES MSF Non Delivery 
___ QIBM_QZMFMSF_SEC_AUT MSFFO100 *YES MSF Security and Authority 
__ QIBM_QZMFMSF_TRK_CHG MSFFO100 *YES MSF Track Mail Message Change 
More... 
Command 
=22> 
F3=Exit F4=Prompt F9=Retrieve F12=Cancel 


L J 


Figure 3-3. Work with Registration Information Display 


You can add, remove, display, or replace exit programs 
using the Work with Exit Programs display. Figure 3-4 
shows that SNA distribution services (SNADS) has a single 
exit program preregistered with this exit point. The other exit 
program is provided by the framework. 


-—— Attention 


Do not add exit program numbers that have exit program 
numbers in multiples of 100 (for example, 100 or 200). 
Multiples of 100 are reserved for IBM use. Do not move 
IBM-supplied exit programs to different positions, change 
the sequence of the exit programs, or change exit point 
program data. 


(For more information about how SNADS uses MSF, see 
Appendix D, “How Mail Server Framework Works with 
SNADS, Object Distribution, and OfficeVision.”) 


(— a 
Work with Exit Programs 
Exit point: QIBM_QZMFMSF_ADR_RSL Format: MSFFO100 
Type options, press Enter. 
l=Add 4=Remove 5=Display 10=Replace 
Exit 
Program Exit 
Opt Number Program Library 
0 
oa 1000 QZDSNPAD Qsys 
— 2000 QZMFSNPA QSYS 
Bottom 
Command 
=a2> 
F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel 
Ke J 


Figure 3-4. Work with Exit Programs Display 


To display details about a specific exit point program, type 5 
in the Opt field next to the exit program you want to display. 
The Display Exit Program display is shown. 


(— > 


Display Exit Program 


System: RCHAS218 
Exit point 2... . 0.6.0 ee ee )~ QIBM_QZMFMSF_ADR_RSL 
Exit point format... ...... 4... :  MSFFO100 
Exit program number. ..........: #21 
Exit program ...... 2.4.44... 2 QZDSNPAD [2] 
LADRARY: 5. seek. eae sec En ek ear ce QSYS 


Text description ............ :  SNADS Address Resolution 
Exit program data CCSID.........: 37 

Exit program data length ........: 24 

Exit program data... ........232 

SPCLO10001A101A201A301C0 


Bottom 
Press Enter to continue. 
F3=Exit 


Fl0=Display data F12=Cancel 


— —_ 


Figure 3-5. Display Exit Program Display 
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Figure 3-6 shows how the output on the display maps to the 
mail server framework. 


Exit Program 


Exit Point 


QSYS/QZDSNPAD 
El ciBv_QZMFMsF_ADR_RSL 2 


El] sPclo100014101A201A301C0 


RV3W168-4 


Figure 3-6. Example of an Exit Program in the Mail Server Frame- 
work 


The exit point name, which is the address reso- 
lution exit point. 


2 | The name of the exit program, which is a 
program associated with the support of the 
SNADS function. See Appendix D, “How Mail 
Server Framework Works with SNADS, Object 
Distribution, and OfficeVision.” 


The exit program data used by the mail server 
framework to select the exit program 
(QSYS/QZDSNPAD). This data consists of a 
format name (SPCLO100), followed by MSF 
address types. These address types are used 
by the framework to determine if the exit 
program (QSYS/QZDSNPAD) should be called. 
Whenever an MSF message having addresses 
of these types in its recipient list is distributed by 
the framework, this exit program is called and 
passed information about the MSF message. 


MSF Configuration APIs 


The mail server framework requires that MSF data types be 
configured. These configured types are stored in internal 
files. There are APIs available to list, add, and remove the 
four data types from the framework. Appendix A, “Mail 
Server Framework APIs” on page A-1 contains a description 
of these APIs. 


When an MSF message is created, the message information 
is assigned data types. The mail server framework validates 
the data types by looking in the internal table. If the data 
type is not configured, the MSF cannot process the 
message. Messages are logged in the job log of the 
program that attempted to use a data type that was not con- 
figured. 


The same is true if an exit point program tries to change a 
message. If the data type is not configured, MSF cannot 
change the message. Messages are logged in the job log of 
the QMSF job in which the exit point program was called. 


In either case, the owner of the failing program needs to look 
for the error in the exit point program. These instances are 
not indications of problems with the mail server framework. 


It is important to note that when the program is changed, or then restart the mail server framework for the changes to 
any configuration changes are made using the MSF config- take effect. 
uration APIs, you must end the mail server framework and 
See “MSF Data Types” on page 5-4 for more information 
about the four data types used by the mail server framework. 
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Chapter 4. Mail Server Framework Structure 


The mail server framework provides the structure to support 
functions that do the work of electronic mail distribution. This 
chapter shows how an MSF message is processed by the 
framework. 


Exit Points 


An exit point is a specific point in a system function or 
program where control may be passed to one or more speci- 
fied exit programs. 


An exit point can call one program, a fixed number of pro- 
grams, or all programs associated with an exit point. An exit 
point contains an exit point name and exit point format name. 


Table 4-1. MSF Exit Points 


MSF Exit Point Description MSF Exit Point Name 


List expansion QIBM_QZMFMSF_LST_EXP 


Address resolution QIBM_QZMFMSF_ADR_RSL 


Envelope processing QIBM_QZMFMSF_ENL_PSS 


Attachment conversion QIBM_QZMFMSF_ATT_CNV 


Security and authority QIBM_QZMFMSF_SEC_AUT 


Local delivery QIBM_QZMFMSF_LCL_DEL 


Message forwarding QIBM_QZMFMSF_MSG_FWD 


Non-delivery QIBM_QZMFMSF_NON_DEL 


Attachment management QIBM_QZMFMSF_ATT_MGT 


Accounting QIBM_QZMFMSF_ACT 
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There are two other exit points, 
QIBM_QZMFMSF_TRK_CHG and 
QIBM_QZMFMSF_VLD_TYP. 


“Exit Point Program Registration” on page 3-1 explains how 
to work with registration information about the exit points 
listed in Table 4-1. 


See the System API Reference book for more information 
about exit points and exit point programs. 


Exit Point Programs 


An exit point program is a program to which control is 
passed from an exit point. Each exit point program is associ- 
ated with an exit point and exit point format. 


Snap-Ins 


An MSF snap-in is an exit point program that is called from 
the mail server framework exit points (see Table 4-1). The 
mail server framework recognizes snap-ins as exit point pro- 
grams. 


The MSF message passes by the exit point if an exit point 
program is not configured for the exit point. The exit point 
program is called by the address types or message types in 
the message. More information about APIs can be found in 
Appendix A, “Mail Server Framework APIs.” For an example 
of how SNADS uses the mail server framework, see 
Appendix D, “How Mail Server Framework Works with 
SNADS, Object Distribution, and OfficeVision.” 
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Exit Points Provided on the Mail Server 
Framework 


The MSF message enters at the top of the framework and 
continues to flow through the framework until it reaches the 
bottom. 


List Expansion List Expansion 
v 
Address Resolution Address Resolution 
v 
Envelope Processing oe Envelope Processing 
v 
Attachment Conversion > Attachment Conversion 
v 
Security and Authority > Security and Authority 
v 
Local Delivery = Local Delivery 
v 
Message Forwarding Message Forwarding 
v 
Non-Delivery Non-Delivery 
v 
Attachment Management 2 Attachment Management 
v 
Accounting Accounting 
(> Exit Point 


=—1 Exit Point Program 
RV3W151-2 


Figure 4-1. MSF Exit Point and Exit Point Program Overview 
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Figure 4-1 shows the exit points provided on the mail server 
framework. The MSF exit points provide a place for an exit 
program to be snapped in. A program that is snapped in at 
an exit point provides the function. These functions are not 
part of the mail server framework. The framework only pro- 
vides the capability to call programs to correct, distribute, or 
log the MSF message information. The mail server frame- 
work uses the results of each of the exit point programs to 
determine which exit program to call next. 


List Expansion List Expansion 1} 
v 
Address Resolution Address Resolution Hl 
: l 
Envelope P 
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Figure 4-2. Using Multiple MSF Exit Point Programs 


Multiple exit point programs can be configured for each mail 
server framework exit point. Figure 4-2 shows multiple exit 
point programs attached to an exit point. 


MSF Exit Point Groups 


It is easiest to think about the exit point programs in terms of 
groups of exit point programs that the exit points call. The 
exit points are described in groups that perform related pro- 


cessing functions. 


| Addressing 


Pre-delivery 
i Processing 


: Delivery 


| Management 


List Expansion 


Address Resolution 


Envelope Processing 


| 


Attachment Conversion 


Security and Authority 


Local Delivery 


Message Forwarding 


Non-Delivery 


Attachment Management 


Accounting 


List Expansion 


Address Resolution 


Envelope Processing 


Attachment Conver: 


sion 


- Security and Authority 


Local Delivery 


Message Forwarding 


Non-Delivery 


Attachment Management 


Accounting 


[> Exit Point 


= — Exit Point Program 


Figure 4-3. MSF Exit Point Groups 


e Addressing group 
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e Delivery group 


The exit point programs in this exit point group resolve 
the addresses of the originator, recipient, report-to, and 


report-on lists. 


The delivery group exit point programs provide local 
delivery or forwarding of an MSF message. 


e Management group 


These exit point programs establish that every recipient 
has a MSF data type and that the recipient list is com- 
plete and correct. The mail server framework continues 
to call these exit point programs until the recipient list 
information is complete. 


e Pre-delivery processing group 


The pre-delivery processing group determines if the MSF 
data type needs to be changed for delivery to take 
place, including envelopes and attachment references. 


This is the clean-up area. The management group exit 


point programs determine what to do with the MSF 
message if it cannot be delivered or forwarded. It 
manages storage used by the MSF message attach- 
ments when the attachments are no longer needed. 
can also log how and when the framework was used, 
track the processing of the MSF message, or provide 
accounting for the MSF message flowing through the 
framework. 
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Exit Point Programs in the Addressing 


Group 
Addressing List Expansion List Expansion 
Address Resolution Address Resolution 
: can Envelope Processing Envelope Processing 
: 
Attachment Conversion Attachment Conversion | 
Security and Authority SS Security and Authority : 
Delwely Local Delivery aE 
Message Forwarding Message Forwarding 
hee et ee ate se ee eee Se ae 
| Management Non-Delivery Non-Delivery 
Attachment Management Attachment Management 
t 
Accounting Accounting 


Figure 4-4. Exit Point Programs in the Addressing Group 


List Expansion Exit Point 


The list expansion exit point calls programs that determine if 
a message recipient address name is the name of a distribu- 
tion list. The name of the distribution list can expand into 
either a list of recipients or more names of distribution lists. 
This exit point calls registered programs based on the 
address type of recipients that do not have a message type 
already assigned to them. A nondeliverable message type is 
assigned to those that do not have a message type already 
assigned. Every message recipient has an address and a 
type associated with the address. The list expansion exit 
point program is configured by address type. When an MSF 
message is being processed that contains recipients with that 
address type, then the program is called. 


For example, a single recipient list address could represent 
the name of a distribution list containing the names of the 
members of a department. A list expansion exit point 
program function could expand the single recipient list 
address into the addresses of the department members. 


To see how exit point programs are configured to be called, 
see Chapter 3, “Configuration Considerations.” 
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Address Resolution Exit Point 


One of the main purposes of any program called by this exit 
point is to assign a message type and message status to 
every MSF message recipient. Recipient message types are 
used to select programs configured in the remaining exit 
points. It allows the user to configure an exit program that 
provides various routing functions. Sometimes the message 
originator does not provide all of the necessary distribution 
information. For example, the exit point program could take 
a partial recipient list, locate it in the directory, and then 
change the recipient information to include the complete 
information required by later exit point programs. 


After all address resolution exit point programs are called, 
the mail server framework checks to see if a recipient list 
entry was replaced or added by a recipient without a 
message type. If this occurred, processing continues at the 
list expansion exit point, allowing the new information to be 
processed. 


If any entries are added to the list either during list expansion 
or address resolution, the processing of the list expansion 
exit point program and the address resolution exit point 
program is recursive. Only the new entries are processed 


because the other entries have already been processed. 
See Figure 4-4. 
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Exit Point Programs in the Pre-Delivery 
Processing Group 


| Addressing List Expansion 


List Expansion 


Address Resolution 


Address Resolution 


Pre-delivery Envelope Processing 


Envelope Processing 


Processing I 


Attachment Conversion 


Attachment Conversion 


Security and Authority 


Security and Authority 


Delivery Local Delivery Local Delivery 
Message Forwarding Message Forwarding 
Management Non-Delivery 


Non-Delivery 


Attachment Management 


Attachment Management 


! 


Accounting Accounting 


Figure 4-5. Exit Point Programs in the Pre-Delivery Processing Group 


Note 


If a recipient list entry does not have a message data 
type at the start of the pre-processing delivery group, the 
recipient list entry is given a nondeliverable status and 
message type. 


Envelope Processing Exit Point 


Any envelope processing program called by this exit point 
allows for message envelope alterations and conversions. 
An envelope is information associated with an MSF 
message and the recipient, such as subject, date and time, 
priority, notes, and special instructions. 


This exit point program uses information about a recipient 
message type and envelope contents. It can provide 
message envelope updates, in addition to converting an 
envelope format into another envelope associated with a 
recipient message type. 
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An envelope processing exit point program can add a new 
envelope type to the MSF message. If this occurs, the mail 
server framework does not call any of the exit point programs 
from previous exit points. An exit program might want to add 
another envelope if there is an exit point program later in the 
mail server framework processing that is designed to use 
that particular type of envelope. 


Attachment Conversion Exit Point 


The programs called by this exit point resolve potential con- 
flicts between the previously resolved message type, and the 
format, structure, or content of the attachments associated 
with the MSF message. For example, a conflict could be 
that the attachments are not in the correct format, not stored 
in the correct file system, or need to be changed so that the 
exit point programs that follow can use the information. This 
exit point allows an attachment conversion exit point program 
to make the required changes to the message attachment 
content. For example, an OfficeVision document could be 
converted to simple ASCII text within this exit point program. 


Security and Authority Exit Point distribution status for each refused recipient (for example, a 
remote recipient) could be changed to nondeliverable or 


The security and authority exit point is available for users to security violation state by the program. 

write exit programs to do specific security and authority 

checking required by a system or mail server. An MSF The exit program can access all information about the 
message could be changed by the user-written exit program message (not the message itself) provided by the mail server 
so all or some of its recipients would not receive the framework. 


message information. To stop such a message, the recipient 
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Exit Point Programs in the Delivery Group 


PRRIPSS ING List Expansion List Expansion 
Address Resolution Address Resolution 
Pre-delivery Envelope Processing Envelope Processing 
Processing | 
Attachment Conversion Attachment Conversion 
Security and Authority Security and Authority 


Delivery Local Delivery Local Delivery 


Message Forwarding Message Forwarding 
Management Non-Delivery Non-Delivery 
Attachment Management Attachment Management 
f 
Accounting Accounting 
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Figure 4-6. Exit Point Programs in the Delivery Group 
Local Delivery Exit Point the message recipient. The framework only decides which 

exit point programs to call and pass the message information 
The programs called by the local delivery exit point provide to. It uses the message types of recipient list entries that 
local delivery of the MSF message. have a remote status to make these decisions. 
As with other MSF exit points, it is possible to configure exit As with other MSF exit points, it is possible to configure exit 
point programs to call or pass recipients that have certain point programs that only call or pass recipients that have 
message types in a message recipient list. The message specific MSF data types assigned to them. The message 
status of the recipient must be a local message status and status of the recipient must be remote and the exit point 
the exit point program must be configured to handle recipi- program must be written to handle recipients with that recip- 
ents with that recipient message type. ient message type. 


: - . Various exit point programs might be written to support 
Message Forwarding Exit Point protocol-specific message forwarding. For example, the 
SNADS message forwarding program forwards an MSF data 
type to remote SNADS recipients by creating a SNADS distri- 
bution and placing the distribution on a SNADS distribution 
queue. A SNADS sender will then do the actual sending of 
the distribution. See the SNA Distribution Services book for 
more information about SNADS distribution. 


The programs called by the message forwarding exit point 
allow an MSF message to be forwarded to remote recipients 
(for example, a mail user not defined on the same AS/400 
system). 


The mail server framework does not forward the message to 
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Exit Point Programs in the Management 


Group 
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Figure 4-7. Exit Point Program in the Management Group 


Non-Delivery Exit Point 


The programs called by the non-delivery exit point report that 
the MSF message was not delivered to its destination or 
recipient. The exit point program allows for the following 
solutions: 


e Logging the distribution that cannot be delivered 


e Routing the nondeliverable messages to a storage area 
where they are kept, corrected, and resent 


¢ Creating a new message to report the non-delivery 


Several things can prevent a message from being delivered. 
Examples include the following: 


e An address resolution exit point program may have a 
partial address of a recipient. The exit point program 
cannot construct a complete address, and the MSF 
message is labeled nondeliverable. 


e The local delivery exit point program or the message for- 
warding exit point program may be configured incor- 
rectly. 


e Recipients may have been marked nondeliverable 
through address resolution processing. 
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e A recipient does not have a message type and was 
marked nondeliverable by the mail server framework. 


Attachment Management Exit Point 


The programs called by the attachment management exit 
point manage the attachments to an MSF message. This 
exit point is used only if there is an attachment reference list 
associated with the MSF message. 


MSF messages only refer to attachments to a message; they 
do not own or manage the storage of the attachments to the 
message. 


Accounting Exit Point 


The programs called by the accounting exit point support the 
system or network accounting functions required in the elec- 
tronic mail environment. The accounting is done after all 
other activity has taken place in the other exit point pro- 
grams. The user can write an exit program that records the 
activity that takes place in the mail server framework. 


This is the last point at which message information is avail- 
able. The mail server framework deletes the internal struc- 
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tures associated with the message as soon as the point program must be written and called to save, deliver, or 
appropriate exit point programs have used the information. forward any message information. 
The MSF message is destroyed after this exit point. An exit 
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Chapter 5. Mail Server Framework Message Concepts 


MSF messages are created when the Create Mail Message 
(QzmfCrtMailMsg) API is used. The framework passes infor- 
mation about the MSF message across the API. The MSF 
message is put on a queue. MSF messages exist until all of 
the appropriate exit point programs have processed them. 


The MSF message contains typed information about the 
message. The mail server framework contains interfaces to 
exit points that deal with the MSF message. 


The MSF message lists and data types allow the framework 
to work with the MSF message information. The MSF 
message can be used or changed only by an exit point 
program when the framework calls it and passes the MSF 
message information to the program. 
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Figure 5-1. MSF Message Concept Overview 
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Originator List 


The MSF message must have an originator list with at least 
one originator entry. Each originator entry is made up of an 
originator address and an originator address type. If more 
than one originating entry is specified when the message is 
created, the mail server framework assumes that all of the 
entries represent the same originator. 


Original Recipient List 


An MSF message can contain a list of all the recipients that 
were originally specified when the message was sent. This 
optional list can be used by applications that, for example, 
want to reply to all recipients of a message. This list is dif- 
ferent from the recipient list in that, as a message moves 
through the network, recipients that are delivered on interme- 
diate systems are removed from the recipient list. However, 
the original recipient list remains intact. 


Recipient List 


An MSF message must have one or more recipient entries. 
When an MSF message is created, the recipient address and 
recipient address type are required fields for each recipient 
entry. 


While the message type in the recipient list entry is not a 
required field for creating a message, it must be assigned to 
a recipient by one of the addressing exit point programs. 
The MSF data type assigned must be in the table of accept- 
able MSF data types for the system. 


The key parts of a recipient list entry are: 


e Address types 
e Message types 
¢ Status field 


Envelope List 


=< 


An MSF message must have one or more envelope entries. 
The message envelope is the information about a particular 
message for a particular protocol type, except for the generic 
envelope type. 


A generic envelope type is defined for any exit point program 
to use. Using the generic envelope type allows an exit point 
program that is processing messages for one protocol type to 
hand over the message to another exit point program that 
processes messages for another protocol type. 


The mail server framework requires that each envelope entry 
contain envelope information and an identifying envelope 
type. The envelope type must be in the table of acceptable 
protocol types for the system. 


Attachment Reference List 


(e4 : 


An MSF message can refer to any number of attachments. 
Each attachment referenced is an entry in the attachment 
reference list. The MSF messages without attachments have 
no attachment reference list. 


The mail server framework requires that each attachment ref- 
erence list contain attachment reference data and a refer- 
ence type. The reference type must be in the table of 


acceptable reference types for the system. For example, a 
reference type can be a database file member or a folder 
document. 


Other Lists 


There are other lists that can be passed to the Create Mail 
Message API. 


Report-On List: The mail server framework requires that 
each report-on list entry contain a non-delivery address and 
a corresponding address type. The address type must be 
configured as a valid address type in the mail server frame- 
work by using the configuration APIs described in “MSF Con- 
figuration APIs” on page A-1. 


Report-To List: The report-to list contains a list of users 
that are sent an error report when an error occurs with a 
message. The mail server framework requires that each 
report-to address entry contain a report-to address and a cor- 
responding address type. An MSF message can have zero, 
one, or multiple report-to address entries. The address type 
must be configured as a valid address type in the mail server 
framework by using the configuration APIs described in “MSF 
Configuration APIs” on page A-1. 


Message Identifier 


The message identifier (ID) is a 32-character unique ID gen- 
erated by the mail server framework when the message is 
created. This ID is used by the exit point programs when 
they are called to retrieve or change information in the MSF 
message. The message identifier cannot be reused. The ID 
is kept with the message and passed to all of the exit point 
programs. 


Chapter 5. Mail Server Framework Message Concepts 5-3 


MSF Data Types 


Message 


The MSF data type is used by the mail server framework to 
define the contents of the data and how the data should be 
processed by the exit point programs. The MSF does not 
process the contents of the message. The framework 
passes the MSF message to the exit point programs for pro- 
cessing. 


MSF data types are used in the exit program data when con- 
figuring exit point programs. Figure 3-6 on page 3-2 shows 
an example of exit program data —jj. 


The MSF data type determines which exit point program 
processes the message and how the MSF message is pro- 
cessed. Figure 5-3 on page 5-5 shows the framework using 
MSF data types to determine which exit point program to 
call. 


There are four data types that are defined by the mail server 
framework. 


e Address type 


The address type is an identifier that indicates the type 
of data that is contained in the address string. The 

address type determines what exit point program to call 
for the list expansion and address resolution exit points. 


e Message type 
The message type is used in the remaining exit points to 
identify which exit point program to call. 

e Envelope type 
The envelope type is an identifier that indicates the type 
of data that is contained in the envelope. 

e Attachment reference type 


The attachment reference type is an identifier that indi- 
cates the type of data that is contained in the attachment 
reference. 


Rules for MSF Data Type Definitions 


Every MSF data type definition is associated with a type 
group, consisting of a data type value, type name, and type 
text. There are IBM-supplied data types predefined in the 
MSF configuration that are shipped with the OS/400 licensed 
program. See AnyMail/400 Mail Server Framework Devel- 
oper Guide for more information about the IBM-supplied data 


types. 
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The data type value is a unique 4-character representation. 
The following type values have special meaning to the mail 
server framework. 


e Oxxx to 9xxx are reserved for use by IBM. 


-—— Important 


It is not recommended to define a data type using 
this range. IBM may, at a later time, add additional 
predefined data types within this range. If a data 
type definition is found in this range and it is not 
supplied by IBM, problems could occur for MSF mail 
applications. 


e 9998 is reserved for use as the nondelivery message 
data type. 


e 9999 is not a data type. It is reserved for use in speci- 
fying that an exit point program is configured to process 
all address or message data types. 


The type name is the name of the data type being config- 
ured. The type text is a description of the data type defi- 
nition. Figure B-12 on page B-11 is an example of a CF 
journal entry, showing the type group, data type value, and 
type name. 


How the MSF Data Types Are Used to Call 
Exit Point Programs 


Exit point programs are called by the mail server framework 
based on the following: 


e MSF data types specified in the exit program data of the 
registered exit point program. 


e MSF data types present in the MSF message recipient 
list entries. 


An exit point program is called and passed information about 
the MSF message so that the program can perform its func- 
tions. 


How the MSF Message Changes 


Exit point programs that are called by the mail server frame- 
work can change the information in an MSF message so 
other exit point programs can see different or additional 
message information. An exit point program can use the 
Change Mail Message (QzmfChgMailMsg) API to make 
changes to the MSF message. These changes have no 
effect until the program returns control to the framework, indi- 
cating that it has finished processing the MSF message suc- 
cessfully. See Figure 5-4 on page 5-5. 


There are some restrictions regarding which exit point pro- 
grams may change an MSF message at certain exit points. 


MSF data type configured 
as exit program data 
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Figure 5-3. MSF Data Types Used to Determine Which Exit Point Program to Call 


Exit Point Program 
called for data 
type 01A1 


O1A1 
——] QzmfC hgMailMsg 


01A1 


Change Mail Message 


Address | 


Recipient List 


Recipient Address 
Changed 


RV3W171-2 


Figure 5-4. Exit Point Programs Can Change Information in an 
MSF Message 


How the MSF Message Flows Through the 
Framework 


A user mail application on the system uses the mail server 
framework Create Mail Message API to create MSF mes- 
sages. The mail server framework inspects the MSF mes- 
sages to ensure that the information is acceptable. 


Once MSF messages are created, they are put on a queue. 
When the mail server framework has been started by the 
Start Mail Server Framework (STRMSF) command, the MSF 
message is processed by the framework. Processing of the 
MSF message is handled by the QMSF job (located in the 
QSYSWRK subsystem). See “Managing MSF Jobs” on 
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page 2-2 for more information about the QOYSWRK sub- 
system. 


The mail server framework decides which exit point programs 
to call at each exit point. The exit point programs can act on 
or change message information that might be used by other 
exit point programs. This does not mean that each message 
uses every registered exit point program; the message data 
types of the recipient determine which exit point programs 
are called. 


It also does not mean that every exit point program called 
uses the MSF message information. The exit point program 
determines that it has no function to perform for that 
message and simply returns it to the framework. 


In Figure 5-5 on page 5-6, the address resolution exit point 
program is the first program called based on the MSF 
address types in the message recipient list. This exit point 
program decides which MSF message types and recipient 
status are assigned to recipients in the message recipient 
list. It changes the recipient list entries. In this example, 
some message recipients are assigned local status and 
some are assigned remote status. 


A local delivery exit point program [J is called by the frame- 
work and passed information in the MSF message. The 
information includes the recipient list entries that have the 
message type (and local status) that the exit point program is 
configured to handle. 


When the program returns, a message forwarding exit point 
program is called and passed information in the MSF 
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message. The information includes the recipient list entries 
that have the message type (and forward status) that the exit 
point program was configured to handle. When the message 
forwarding program returns, the framework determines if 
other exit point programs at the remaining exit points should 
be called based on the message types in the message recip- 
ient list. In this example, there are no additional exit point 
programs to be called so the MSF message is removed. 


Figure 5-5 shows three exit point programs cooperating in 
delivering MSF message information to local recipients and 
forwarding that information to remote recipients in its recip- 
ient list. There could be more exit point programs configured 
but not part of the example message flow because the MSF 
data types did not result in a call to these exit point pro- 
grams. 
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Figure 5-5. How an MSF Message Flows Through the Framework 


Appendix A. Mail Server Framework APIs 


This appendix describes the mail server framework APIs. 
For more information about the required parameter groups, 
message descriptors, message descriptor formats, and error 
messages, see the System AP! Reference book. 


The following APIs are made up of program calls: 


MSF configuration APIs 
Add Mail Server Framework Configuration 
(QzmfAddMailCfg) 
List Mail Server Framework Configuration 
(QzmfLstMailCfg) 
Remove Mail Server Framework Configuration 
(QzmfRmvMailCfg) 

Message APIs 
Create Mail Message (QzmfCrtMailMsg) 
Change Mail Message (QzmfChgMailMsg) 
Retrieve Mail Message (QzmfRtvMailMsg) 
Complete Creation Sequence 
(QzmfCrtCmpMailMsg) 
Query Mail Message Identifier (QzmfQryMailMsgld) 
Reserve Mail Message Identifier 
(QzmfRsvMailMsgld) 
Remove Reserved Mail Message Identifier 
(QzmfRmvRsvMailMsgld) 


The mail server framework also provides three exit points 
where the following exit programs are used: 


Snap-In Call Exit Point Program 
Track Mail Message Changes Exit Point Program 
Validate Data Field Exit Point Program 


MSF Configuration APIs 


The MSF configuration APIs are used to process type config- 
urations within the mail server framework configuration. The 
following processes can be performed: 


e Adding to the configuration 
e Removing from the configuration 
e Listing the contents of the configuration 


These APIs are used to add or remove new mail application 
support in the framework or to list the current configuration. 


Exit point programs can also access the trace information 
that contains an account of all the exit point programs used 
in the framework and those that changed the message by 
using the Retrieve Mail Message (QzmfRtvMailMsg) API. 
The framework does not record the exact changes made to 
the message. The Track Mail Message Changes Exit 
Program is called whenever an exit point program changes 
the message and a program is registered for the exit point. 
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Add Mail Server Framework Configuration 
(QzmfAddMailCfg) API 


The Add Mail Server Framework Configuration 
(QzmfAddMailCfg) API configures the MSF data types used 
by the mail server framework to process messages. The fol- 
lowing data types are valid: 


e Address 

e Message 

e Envelope 

e Attachment reference 


This API also configures the address type and message type 
that can be specified as exit program data in the user-written 
exit program. 


The MSF data type is used to process the MSF message 
through the framework. Only one data type can be added at 
atime. See “MSF Data Types” on page 5-4 for more infor- 
mation about the four data types. 


List Mail Server Framework Configuration 
(QzmfLstMailCfg) API 


The List Mail Server Framework Configuration 
(QzmfLstMailCfg) API creates a list of data types and places 
the list in a specified user space. 


Remove Mail Server Framework 
Configuration (QzmfRmvMailCfg) API 


The Remove Mail Server Framework Configuration 
(QzmfRmvMailCfg) API removes MSF data types that the 
mail server framework uses to process MSF messages. The 
MSF data type is removed from the configuration when this 
API is used. Only one data type can be removed at a time. 
See “MSF Data Types” on page 5-4 for more information 
about the four data types. 


MSF Message APIs 


The MSF message APIs are used to create an MSF 
message and ensure delivery of the message. These APIs 
are used by user-written exit programs. 


Create Mail Message (QzmfCrtMailMsg) 
API 


The Create Mail Message (QzmfCrtMailMsg) API creates an 
MSF message. When an MSF message is created, the fol- 
lowing lists can be specified: 


¢ Originator (required) 
e Recipient (required) 
e Envelope (required) 


e Attachment reference 
e Report-on 

e Report-to 

¢ Original recipient list 
e Reply-to list 


The format of the data is defined by assigning a type to the 
information. The MSF data types need to be configured 
before they can be supported. There are four MSF data 
types. 


e Address type 

e Message type 

e Envelope type 

e Attachment reference type 


See Chapter 5, “Mail Server Framework Message Concepts 
for more information about MSF lists and MSF data types. 


Change Mail Message (QzmfChgMailMsg) 
API 


The Change Mail Message (QzmfChgMailMsg) API changes 
information about an MSF message that was previously 
created using the Create Mail Message API. Each time it is 
called, the Change Mail Message API can change one or 
more list items for each of the message parameter list 
formats. For example, one call can result in changes to the 
envelope list, the recipient list, and the attachment reference 
list. An exit program can be written to change an MSF 
message. If the requested changes are acceptable, the 
existing list items are replaced with the new items that are 
specified. The list items do not retain their same unique list 
identifiers after the changes are complete. 


Figure 5-4 on page 5-5 shows an example of how the MSF 
message changes when this API is used. 


Note: The Change Mail Message API is only valid within 
the processing of a Snap-In Call Exit Point Program. 


Retrieve Mail Message (QzmfRtvMailMsg) 
API 


The Retrieve Mail Message (QzmfRtvMailMsg) API retrieves 
information about an MSF message and returns it in the 
receiver variable provided by the caller. 


Note: The Retrieve Mail Message API is only valid within 
the processing of a Snap-In Call Exit Point Program or the 
Track Mail Message Changes Exit Point Program. 


Other Optional APIs 


Query Mail Message Identifier (QzmfQryMailMsgld) 
API: The Query Mail Message Identifier 
(QzmfQryMailMsgld) API is used to query the status of a 
mail message identifier within the mail server framework. 


A-2 AnyMail/400 Mail Server Framework Support V4 


Reserve Mail Message Identifier 
(QzmfRsvMailMsgld) API: The Reserve Mail Message 
Identifier (QzmfRsvMailMsgld) API is used to reserve an 
identifier for an electronic mail message. 


Complete Creation Sequence 
(QzmfCrtCmpMailMsg) API: The Complete Creation 
Sequence (QzmfCrtCmpMailMsg) API removes a previously 
created, reserved mail message identifier from the MSF list 
of reserved identifiers and acknowledges that the MSF 
message was created. 


Remove Reserved Mail Message Identifier 
(QzmfRmvRsvMailMsgld) API: The Remove Reserved 
Mail Message Identifier (Q2mfRmvRsvMailMsgld) API 
removes a reserved identifier for an electronic mail message 
that you have not yet created. If the message was created, 
you must use the Complete Creation Sequence API to 
release the reserved message. After the Remove Reserved 
Mail Message Identifier AP! completes successfully, you 
cannot use the message identifier you reserved earlier when 
the message was created. 


Exit Points 


The mail server framework provides three exit points where 
the following exit programs are used. 


Snap-in Call Exit Point Program 


The Snap-In Call Exit Point Programs process the electronic 
mail within the framework. 


Track Mail Message Changes Exit Point 
Program 


In some cases, the user may want to track the changes 
made to a message. The Track Mail Message Changes Exit 
Program can be used. Whenever a message is changed by 
an exit point program, an exit program registered for this exit 
point is called and the following information is passed: 


e The message identifier 

e The exit point name being processed when the change 
was made 

e The exit point program name responsible for the change 


Validate Data Field Exit Point Program 


The Validate Data Field Exit Point Program allows exit pro- 
grams to validate the data for a message based on the MSF 
data type selected. As part of the mail server framework 
configuration, MSF data types must be defined to the 
system. 


Appendix B. MSF Journal Logging and Journal Formats 


This appendix provides information about the journal support 
used by the mail server framework. 


uration of MSF types or exit programs takes place; this entry 
is type CF. 


QZMF Journal 


The mail server framework uses OS/400 journal support to 
track MSF configuration changes and MSF message pro- 
cessing performed on the local system by the mail server 
framework. 


A journal (QZMF) is shipped with security officer authority in 
the QUSRSYS library. The journal name used for the mail 
server framework must be QZMF. QZMF uses a journal 
code of S. Code S is a distributed mail service for SNA dis- 
tribution services (SNADS), network alerts, or the mail server 
framework. For the QZMF journal, this code always means 
the mail server framework. 


There are four types of MSF journal entries: 


LG MSF message log information for the mail server 
framework. A normal function, such as creating or 
completing an MSF message, was successfully per- 
formed. 


ER MSF message error information for specific MSF 
messages in the mail server framework. The MSF 
message could not be completed because of a 
framework or exit point program error. 


SY MSF system information for the mail server frame- 
work. 

CF Configuration information for the mail server frame- 
work. 


An output file for each type of entry is provided that shows 
the data for each entry. This file enables you to copy the 
information to an output file using the Display Journal 
(DSPJRN) command. Specify *TYPE1 for the outfile format 
(OUTFILFMT) parameter. 


You are responsible for changing the QZMF journal receiver 
with the Change Journal (CHGJRN) command. You can do 
this when the receiver is full, or at any convenient time. 


When an MSF message is created or processed by the mail 
server framework successfully, a journal entry, type LG, is 
made on the system. If an error occurs when processing an 
MSF message, an error entry, type ER, is made in the QZMF 
journal. SY entries record significant events that may affect 
MSF functions, for example when the STRMSF or ENDMSF 
commands are used. An entry is made whenever a config- 
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Displaying the QZMF Journal 


You can view the MSF journal entries by using the Display 
Journal (DSPJRN) command. Type DSPJRN on the command 
line and press F4. You are prompted for the information you 
want to see. You can enter specific parameters and options 
or take the default values for each of the prompted parame- 
ters. 


[ Display Journal (DSPJRN) | 


Type choices, press Enter. 


JouviNnal, soa te we, ewe AA QZMF Name, *INTSYSJRN 
LUD RAT YE modes, ne es ema od cr a *LIBL Name, *LIBL, *CURLIB 
Journaled physical file: 
TNO e pe i ce as Se chee hl PR eS *ALLFILE Name, *ALLFILE, *ALL 
ER DRARY! oa fe man ne eck Name, *LIBL, *CURLIB 
Member... ......2.008- Name, *FIRST, *ALL 
+ for more values 
Range of journal receivers: 
Starting journal receiver .. *CURRENT Name, *CURRENT, *CURCHAIN 
ib Rany” Ae. ocd: an ein Oe Gos Name, *LIBL, *CURLIB 
Ending journal receiver ... Name, *CURRENT 
LIBRARY. ~ bese de ea ae Name, *LIBL, *CURLIB 
Starting sequence number... . *FIRST Number, *FIRST 


Starting date and time: 


Starting date ........ 01/16/95 Date 
Starting time ........ 08:00:00 Time 
More... 
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display 


F24=More keys 


E J 


Figure B-1. Display Journal - First Display 


Display Journal (DSPJRN) 


Type choices, press Enter. 


Ending sequence number... .. *LAST Number, *LAST 
Ending date and time: 
Ending date ......... 01/16/95 Date 
Ending time ......... Time 
Number of journal entries ... *ALL Number, *ALL 
Journal codes: 
Journal code value. ..... S *ALL, *CTL, A, C, F, J, L... 


Journal code selection... 


: *ALLSLT, *IGNFILSLT 
+ for more values 


Journal entry types ...... *ALL Character value, *ALL, *RCD 
+ for more values 

Job name. .........24- *ALL Name, *ALL 

USOT ee aac Sa ote wr es po Bad cae Name 

NUMD OT ES Pe Mie ete eran On ove 000000-999999 
PHOOTAMNS Vac ccmmecne® “ha RAG! Taiecetne, 2's *ALL Name, *ALL 
User’ profile oo: s ve spies ee a a *ALL Name, *ALL 

More... 

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display 


F24=More keys 


en, 


Figure B-2. Display Journal - Second Display 
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Display Journal (DSPJRN) 
Type choices, press Enter. 


Commit cycle identifier .... *ALL Number, *ALL 


Dependent entries ....... *ALL *ALL, *NONE 
Output format ......... *CHAR *CHAR, *HEX 
QUEPUE 6 ee me CR er ee * *, *PRINT, *OUTFILE 


Bottom 


F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display 


F24=More keys 


— — 


Figure B-3. Display Journal - Third Display 


The following specifies the parameters and the options avail- 
able for MSF entries. 


e Range of journal receivers: Specifies the starting 
(first) and ending (last) journal receivers that contain the 
journal entries being converted for output. 


¢ Starting sequence number. Specifies the first journal 
entry to be considered for conversion for output. You 
can specify *FIRST to display the entire journal receiver 
range or you can specify a specific sequence number to 
be converted. 


¢ Starting date and time: Specifies the date and time of 
the first journal entry. 


— Starting date: The format for the date is defined by 
the job attributes DATFMT and, if separators are 
used, DATSEP (for example, 01/16/95). 


— Starting time: The time is specified in 24-hour 
format and can be specified with or without a time 
separator (for example, 08:00:00). 


These fields are very useful because they segment the 
QMSF journal entries into specific windows of interest. 
For example, if you want to display all entries that 
occurred on 05/24/95, starting at 11:00 a.m., specify the 
starting date of 05/24/95 and the starting time of 
11:00:00, and then press the Enter key. 


¢ Ending sequence number. Specifies the last journal 
entry to be considered for conversion. You can specify 
*LAST to display the final journal receiver being con- 
verted or you can specify a specific sequence number to 
be converted. 


e Ending date and time: Specifies the date and time of 
the last journal entry. 


— Ending date: The format for the date is defined by 
the job attributes DATFMT and, if separators are 
used, DATSEP (for example, 05/30/95). 
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— Ending time: The time is specified in 24-hour format 
and can be specified with or without a time sepa- 
rator (for example, 08:00:00). 


e Journal codes: For the mail server framework entries, 
this code will always be S. No other codes are used by 
MSF. 


e Journal entry types: For the mail server framework, 
the following entries are used: 


LG: MSF message log information entries 
ER: MSF message error information entries 
SY: MSF message system information entries 
CF: MSF configuration information entries 


You can specify any combination of codes. For 
example, you can specify that you only want to see the 
LG and ER entries. The default displays all entries. 


e Job name: Specify QMSF or the user job name (for 
example, QPADEV0007) to show the jobs running for 
the mail server framework. 


Displaying the Journal Entries 


From the Display Journal display, press the Enter key to see 
the Display Journal Entries display. The information con- 
tained on this display depends on the parameters and values 
you specified (including default values taken). The entries 
are always displayed in chronological order. The following is 
an example of the display: 


[ Display Journal Entries | 


Journal ...... : QZMF Library ...... :  QUSRSYS 
Type options, press Enter. 
5=Display entire entry 

Opt Sequence Code Type Object Library Job Time 
1 oJ PR DSPO 9:15:28 
3 OJ RR = QZMF QUSRSYS 9:42:51 
4 J IN 22:21:06 
5 J IN 1:43:28 
6 6S SY QPADEVOO07 12:43:31 
7 S$ SY QPADEVOO07 13:01:42 
8 S SY QPADEVOO08 = 14:10:22 
9 S SY QPADEVOO08 = 14:10:31 
10 6S SY QPADEVO008 = 14:10:33 
ll 6S SY QPADEVOOO8 = 14:13:27 
12. «6S SY QPADEVOO08 =14:13:34 
13° =¢«S SY QPADEVOO08 = 14:13:35 + 

F3=Exit F12=Cancel 


E 5 


Figure B-4. Display Journal Entries Display 


This sample display was shown with default values specified 
for all of the parameters. As a result, there are different 
codes, different entry types, and different jobs listed. 


If the data in the record does not fit on one display, use the 
page keys to advance to subsequent displays or to return to 
a previous display in the series. A plus sign (+) in the lower 
right corner of the display indicates that there are more dis- 
plays in the series. 


Note: If there are no entries in the journal receiver that 
match the values on the entered parameters, this message 
appears on the display: 


(No log entries). 


This condition can occur when the log entries are sent to the 
journal receiver during a time when the system clock is set to 
an incorrect date or time. You would be unable to find 
entries for a specified range when you use a range search to 
search the affected journal receiver. Use the Change 
Journal (CHGJRN) command to create a new journal 
receiver. Creating a new journal receiver (once the system 
clock has been set to the correct time) ensures that the 
current journal receiver entries have the correct time. This 
command has no effect on old journal receivers. 


From the Display Journal Entries display, you can type a 5 
(Display entire entry) in the Opt field to see the detail for 
each entry. The information available in the detail is different 
for each entry type, so the detail has a unique display based 
on the entry type. The following are examples of detail dis- 
plays for different function and entry types. 


Entry Type LG: This display is shown when you type a 5 
(Display entire entry) on the Display Journal Entries display 
next to an entry that has function type LG (logging). “Format 
for MSF Message Logging (LG)” on page B-5 provides 
detailed information about the contents of this display. 


Display Journal Entry 


OD JOE E ise. doce Gene viek 90 8 LADRARY cers ee Cee OF 
Member... 1... 232 Sequence. .....: 3380 
Codes3: 8 4k A AS S - Distributed mail services 

TY PC hein ee ele oa LG - Mail logging table information 


Entry specific data 
Column EE eee ee SIH Peek eee PERE E, Cee 
00001 "QMSF QMSF 006000QZMFBIGEZID 100003394051! 
00051 '52158420000000009 | 


Bottom 
Press Enter to continue. 
F3=Exit F6=Display only entry specific data 
Fl0=Display only entry details F12=Cancel F24=More keys 
hee a, 


Figure B-5. Display Journal Entry - Type LG 


Entry Type ER: This display is shown when you type a 5 
(Display entire entry) on the Display Journal Entries display 
next to an entry that has function type ER (error). “Format 
for MSF Message Errors (ER)” on page B-7 provides 
detailed information about the contents of this display. 


ii Display Journal Entry | 


ObFCC EHR tee er ey eect i bKARy: 065.32 re nce ee 8 
Member. ......3 Sequence. .....: 3395 
Codes oie 8 ee te aS S - Distributed mail services 
TYPO se erect eee eit ER - Mail error information 

Entry specific data 
Column ERA AA Ie CRE AEST EE CO ECOL RET) 
00001 "QMSF QMSF Q06000QZMFBIGEZID 100003394051' 


00051 '61305090000000015 CAPITST DEBPGM : 


Bottom 
Press Enter to continue. 


F3=Exit F6=Display only entry specific data 
Fl0=Display only entry details F12=Cancel F24=More keys 


L 5 


Figure B-6. Display Journal Entry - Type ER 


Entry Type SY: This display is shown when you type a 5 
(Display entire entry) on the Display Journal Entries display 
next to an entry that has function type SY (system). “Format 
for MSF System Level Events Table (SY)” on page B-8 pro- 
vides detailed information about the contents of this display. 


[ Display Journal Entry | 


ODJOCE: ae eookseye Ge a 8 Library = 2.6 ee Ao 
Member... ....3: Sequence... .. 5. 3715 
CODE ee ae etree 8 SE S - Distributed mail services 
Type v. ose eat t SY - Mail system information 

Entry specific data 
Column Hache iets Pic leacet aves decns Pewwe beast nice D: 
00001 "QPADEVOO07BANER 006163QZMFEEND5 ' 


Bottom 
Press Enter to continue. 


F3=Exit F6=Display only entry specific data 
Fl0=Display only entry details F12=Cancel F24=More keys 


——— 


Figure B-7. Display Journal Entry - Type SY 
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Entry Type CF: This display is shown when you type a 5 
(Display entire entry) on the Display Journal Entries display [_ Display Journal Entry | 
next to an entry that has the entry type CF (configuration). Sets oan DRA ce. pidsesA 
“Format for MSF Configuration Changes (CF)” on page B-9 Member»... 2 1 2: Sequence... ... : 3690 
. 7 . 3 Code... .....: + S - Distributed mail services 
provides detailed information about the contents of this Type... .... 3: CF - Mail configuration information 
display. Entry specific data 
Column #5 seks sisdeats. cobsieisesivets seedesaiet tea sbates ehhisaD 
00001 "QPADEVO007BANER 006163QZMFDLTC4 0101TTO1T' 
00051 "TNAME' 
Bottom 
Press Enter to continue. 
F3=Exit F6=Display only entry specific data 
Fl0=Display only entry details F12=Cancel F24=More keys 


L J 


Figure B-8. Display Journal Entry - Type CF 
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Format for MSF Message Logging (LG) 


The entry is made when a MSF message is created, reset, 
or completed. The entry is mapped by the database file 
record, QAZMFLG, that represents the MSF message log 
information entered. This record is defined by the physical 
file QAZMFLG, which is shipped in QSYS library. The 
LG-type journal entry contains the following information: 


Table B-1. Type LG Journal Entries for MSF Messages 


Field Format Description 

Entry length Zoned(5,0) Total length of the journal entry, including the entry length field. 

Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when 
a new receiver is attached. 

Journal code Char(1) Always S for MSF entries. 

Entry type Char(2) Always LG for MSF message entries. 

Date stamp Char(6) The system date that the entry was made. 

Time stamp Zoned(6,0) The system time that the entry was made. 

(Reserved area) Char(95) 

Job name Char(10) The name of the job that caused the entry to occur. 

User name Char(10) The user profile name associated with the job. 

Job number Zoned(6,0) The job number. 

Program name Char(8) The name of the MSF program that made the journal entry. 

Function identifier Char(1) Function that was being performed when the entry was made. The possible values are: 
1 MSF message created log entry 
2 MSF message ended normally 
3 MSF message reset by STRMSF command (STRMSF MSGOPT(*RESET)) 
4 MSF message removed by STRMSF command (STRMSF MSGOPT (*CLEAR)) 
5 MSF message acted on by address switcher 

MSF message ID Char(32) The MSF message ID logged. 

Length of entry data Zoned(5,0) The length of the logged data. 

Logged data Char(256) The data logged by MSF when the function identifier is: 


2 Data is three Zoned(5,0) numbers. The first number is the number of entries in the 
recipient list when the message was created. The second number is the number of 
entries in the recipient list when processing was completed for the message. The 
third number is the number of recipients that had a non-deliverable status when 
processing was completed for the message. 

5 Data is two Zoned(5,0) numbers. The first number is the number of recipients that 
had their address switched by program QZMFSNPA. The second number is the 
total number of recipients that were in the recipient list of the MSF message pro- 
cessed by QZMFSNPA. 
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Figure B-9 is an example LG journal entry you might see 


when you use option 5 on the Display Journal Entries display 
to display the entire entry. The values of any QZMF journal 


entry field can be mapped to the entry data displayed. 
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Job Name, MSF 
User Name, Program Function Message 
Job Number Name Identifier ID 


Display Journal Entry 


Object. « 6 sa 6 « Library ..\....3: 
Member... ... A: Sequence 3380 
Code: a thon ee a NS S - Distributed mail service 
TYP@ 6%. 6 ete wm LG - Mail logging table information 

Entry speaific data 
Column Wiebe ed ledvctesn les octes edusas Heine bated tecancd 
00001 {QMSF QMSF 006000|QZMFBIGE] 2/I1D 100003394051" 
00051 "52158420000000009] | 000010000100000'| 
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Logged Data 
Figure B-9. Fields of the Journal Entries - Example 


Format for MSF Message Errors (ER) 


The entry for MSF message errors is mapped by the data- 
base file record, QAZMFER, that represents the error infor- 
mation entered. This record is defined by the physical file 
QAZMFER, which shipped in QSYS. The ER type journal 


entry contains the following information: 


Table B-2. Type ER Journal Entries for MSF Message Errors 


Field Format Description 
Entry length Zoned(5,0) Total length of the journal entry, including the entry length field. 
Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when 
a new receiver is attached. 
Journal code Char(1) Always S for MSF entries. 
Entry type Char(2) Always ER for MSF message error entries. 
Date stamp Char(6) The system date that the entry was made. 
Time stamp Zoned(6,0) The system time that the entry was made. 
(Reserved area) Char(95) 
Job name Char(10) The name of the job that caused the entry to occur. 
User name Char(10) The user profile name associated with the job. 
Job number Zoned(6,0) The job number. 
Program name Char(8) The name of the MSF program that made the journal entry. 
Error ID Char(1) The MSF error ID. The possible values are: 
2 MSF message ended by an exit program 
3 QMSF job ended by an exit program 
4 An exit program returned data that was not valid 
5 An exit program failed 
MSF message ID Char(32) The MSF message ID logged. 
Data length Char(5) The length of the logged data. 
Logged data Char(256) The data logged by MSF when the error ID is: 


2 


3 
4 
5 


Exit program name char(10) and library char 

Exit program name char(10) and library char’ 

Exit program name char(10) and library char 
(10) 


(10) 
(10) 
(10) 
Exit program name char and library char(10) 


Figure B-9 on page B-6 shows an example of how the fields 
defined for QZMF journal entries are mapped to the dis- 


played data. 
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Format for MSF System Level Events 


Table (SY) 


entries to be made in the MSF journal. The SY-type journal 
entry contains the following information: 


The entry for system level events table change is shown by 
the database file record, QAZMFSY, which represents MSF 
system name table entries. This record is defined by the 
physical file QAZMFSY, which is shipped in the QSYS 
library. Various mail server framework functions cause 


Table B-3. Type SY Journal Entries for the MSF System Level Events Table Changes 


Field Format Description 
Entry length Zoned(5,0) Total length of the journal entry, including the entry length field. 
Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when 
a new receiver is attached. 
Journal code Char(1) Always S for MSF entries. 
Entry type Char(2) Always SY for MSF system level events entries. 
Date stamp Char(6) The system date that the entry was made. 
Time stamp Zoned(6,0) The system time that the entry was made. 
(Reserved area) Char(95) 
Job name Char(10) The name of the job that caused the entry to occur. 
User name Char(10) The user-profile name associated with the job. 
Job number Zoned(6,0) The job number. 
Program name Char(8) The name of the MSF program that made the journal entry. 
Function identifier Char(1) Function that was being performed when the entry was made. The possible values are: 
1 STRMSF command started (QMSF jobs) 
2 Internal tables initialized (part of STRMSF command function) 
3 Internal queues initialized (part of STRMSF command function) 
4 Space pool index created and initialized 
5 ENDMSF command started (ended QMSF jobs) 
6 Damaged or destroyed internal space found 
7 Message destroyed by using DATAAREA QZMFKQ value 
8 Abnormal IPL destroyed in internal MSF space index 
9 MSF clean up functions (part of Reclaim Storage (RCLSTG) command) started 
A MSF space clean up function started 
B MSF clean up functions completed 
Cc MSF reclaim storage function ended 
Data length Zoned(5,0) The length of the logged data. 
Logged data Char(256) The data logged by MSF when the function identifier is: 


6 32 character MSF message ID 
7 32 character MSF message ID followed by total number of internal entries 
destroyed 


Figure B-9 on page B-6 shows an example of how the fields 
defined for QZMF journal entries are mapped to the dis- 


played data. 
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Format for MSF Configuration Changes 


(CF) 


The entry for MSF configuration change is mapped by the 
database file record, ZMFXCFFT, which represents the 
change made. This record is defined by physical file 
QAZMFCF, which is shipped in the QSYS library. The 
CF-type journal entry contains the following information: 


Table B-4. Type CF Journal Entries for MSF Configuration Changes 


Field Format Description 
Entry length Zoned(5,0) Total length of the journal entry, including the entry length field. 
Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when 
a new receiver is attached. 
Journal code Char(1) Always S for MSF entries. 
Entry type Char(2) Always CF for MSF configuration change entries. 
Date stamp Char(6) The system date that the entry was made. 
Time stamp Zoned(6,0) The system time that the entry was made. 
(Reserved area) Char(95) 
Job name Char(10) The name of the job that caused the entry to occur. 
User name Char(10) The user profile name associated with the job. 
Job number Zoned(6,0) The job number. 
Program name Char(8) The name of the MSF program that made the journal entry. 
Function identifier Char(1) Function that was being performed when the entry was made. The possible values are: 
1 MSF data type configured added to configuration database by QZMFCOPN 
program. MSF type tables initialized with shipped type definitions. 
2 Reserved. 
3 Added configuration to the configuration database. New MSF data type defined by 
using the QzmfAddMailCfg API. 
4 Configuration removed from the configuration database. MSF data type removed 
by using the QzmfRmvMailCfg API. 
5 Exit program removed from MSF exit point. 
6 Exit program added to MSF exit point, except QIBM_QZMFMSF_VLD_TYP and 
QIBM_QZMFMSF_TRK_CHG. 
7 Exit program added to QIBM_QZMFMSF_VLD_TYP or 
QIBM_QZMFMSF_TRK_CHG. 
A Install program started. 
B Install program ended. 
Cc Type not deleted during install. 
D Type not added during install. 
E Exit point program not deleted during install. 
Exit point program not added during install. 
Data length Zoned(5,0) The length of the logged data. 
Logged data Char(256) The data logged by MSF when the function identifier is: 


1 The record for the MSF data type that was added. 

3 The record for the MSF data type that was added. 

4 The record for the MSF data type that was removed. 

5 The information about the MSF exit point program that was removed during install. 

6 The information about the MSF exit point program that was added during install. 

7 The information about the MSF exit point program that was added during install. 

Cc The record for the MSF data type that the install program failed to delete. 

D The record for the MSF data type that the install program failed to add. 

E The information about the MSF exit point program that the install program failed to 
delete. 

F The information about the MSF exit point program that the install program failed to 
add. 
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Figure B-9 on page B-6 shows an example of how the fields 
defined for QZMF journal entries are mapped to the dis- 
played data. 
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Figure B-10 shows an example of how the A function identi- 
fier field is mapped to the displayed data. 


Function 
Identifier 


| 
| 


\ 


Display Journal Entry 


Object: 6: ee see et eS ON ae RSS 
Member... ....: Sequence. ..... : 2217 
Code «ce eee ye I S - Distributed mail] services 
TYP@! a6. woes ew es CF - Mail configuration information 

Entry specific eee | 
Column ie Pantie lagtie's Pee ire ee oe ee ae: 


00001  PADEVOOUSSANER 007575QZMFXLOGA |" 


RV3W176-1 


Figure B-10. Function Identifier A - Example 


Figure B-11 shows an example of how an B function identi- 
fier field is mapped to the displayed data. 


Function 
Identifier 


\ 
\ 


\ 
Display Journal Entr 


Object. .....03 Libnary 2... 2... : 
Member. ......: Sequence... . . . : 2223 
COdE: sia koe: see ve ar ad S - Distributed maill services 
TYP: se ap 8. Me sees CF - Mail configuration information 
amy Sree cota 

Column Ra vidtiaasiale.aieioPsraseis Qoicet nee Sicca even iweste vend 
00001 i ner 007575QZMFXLOGB | ' 

RV3W177-1 


Figure B-11. Function Identifier B - Example 


Figure B-12 shows an example of how an D function identi- 
fier field is mapped to the displayed data. The C and D func- 
tion identifier entries look identical. 


Data 
Function Type Type 
Identifier Group Value 


Display Journal Entry 
Object cise jj —\ blbraty wae kc «a & 
Member. ......: £\Sequente..h. ...: 2218 
Codes. «is we wee SB S - Distributed mail services 
TYPE & oe ee we a CF - Mail configu nformation 
Entry specific bis 
Column Po icretire relicgnct emis Lee bigs Dees iu 
00001 QbADEVOROTAANER 007575QZMFXLOGD| {01/]01C0|01COADD' 
00051 'D' | 
RV3W178-1 
Type 
Name 


Figure B-12. Function Identifier D - Example 


Figure B-13 shows an example of how an F function identi- 
fier field is mapped to the displayed data. The E and F func- 


tion identifier entries look identical. 


Function Exit 
Identifier Point 
| 
| 
| 
Display Journal Entry | 
Object... ee ee fad Library .. ste ses 
Member. ...... : equence...|.. 2220 
COd@ ss a a eH SE S - Distributed\mail services 
Type... ..... : CF - Mail configuration information 
Euety SpECIP TE. data an 
Column —s *.... . 4... Viviedtte cess Livestoess dens Vt : 
00001 SG eEVOONSHINER 007575QZMFXLOGF ‘Gincaaese QZMFWSF_ [QIBM_QZMFMSF_' 
00051 TRK_CHG|MSFFO100 9000| DEBTRACKTR|QSYS | 
RV3W179-1 
Exit Exit Exit Exit 
Point Program Point Point 
Format Number Program Program 
Library 


Figure B-13. Function Identifier F - Example 
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Appendix C. Preregistered Exit Point Programs 


The exit point programs shipped with MSF are preregistered 
when you install your AS/400 system. These preregistered 
programs are shown in Figure C-1. 


Exit 
Exit Program 
Program Number 


Mail Server Framework 


List Expansion QSYS/QZDSNPLE 1000 


t QSYS/QZMFSNPA | 2000 
Address Resolution QSYS/QZDSNPAD /|1000 


| 


Local Delivery QSYS/QZDSNPLD 1000 


yo 
2 
t 
Message Forwarding > 
| 
| 


QSYS/QZDSNPMF 1000 


! 


Non-Delivery 


! 


Attachment Management 


Accounting - 


QSYS/QZDSNPND 1000 


QSYS/QZDSNPAM 1000 


QSYS/QZDSNPAC_ 1000 
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Figure C-1. Exit Point Programs Shipped with MSF 


On the Work with Registration Information display, type 8 in 
the Opt Field next to the address resolution exit point, 
QIBM_QZMFMSF_ADR_RSL. The Work with Exit Programs 
display containing information about the address resolution 
exit point is shown, as in Figure C-2. The two programs, 
QZDSNPAD and QZMFSNPA, are the address resolution 
handler and the switcher programs. 


© Copyright IBM Corp. 1997 


[ Work with Exit Programs | 


Exit point: | QIBM_QZMFMSF_ADR_RSL Format: MSFFO100 


Type options, press Enter. 
1=Add 4=Remove 5=Display 10=Replace 


Exit 


Program Exit 
Opt Number Program Library 
0 
= 1000 QZDSNPAD Qsys 
a, 2000 QZMFSNPA QSYS 


Bottom 
Command 
===> 


F3=Exit F4=Prompt F5=Refresh F9=Retrieve  F12=Cancel 


Lo 


Figure C-2. Address Resolution Exit Point Programs 


Exit Program QZMFSNPA 


For those recipients of a MSF message who do not have a 
MSF data type assigned by previous address resolution exit 
point programs, a preregistered default exit point program is 
called. This preregistered address resolution exit point 
program, QZMFSNPA, changes the recipient list addresses 
to their preferred addresses and address types, as specified 
in the system distribution directory. The exit point program 
uses the directory search API (QOKSCHD) to determine the 
preferred addresses and address types of the message 
recipients. An example is shown in Figure C-3 on page C-2. 


-— Note 


For any exit point program, including QZMFSNPA, to use 
the directory search API (QOKSCHD), the directory must 
allow searches. The Change System Directory Attributes 
(CHGSYSDIRA) command can be used to specify that 
directory searches are allowed by changing the ALWSCH 
parameter to *YES. If directory searches are not 
allowed, QZMFSNPA issues error message CPFAF90, 
which indicates the QMSF job will end. 


See the SNA Distribution Services book for more information 
about preferred addresses. 


C-1 


OtAt 


Addresst 


Address Resolution Exit Point 


AS <———>—_ 


QSYS/QZMFSNPA Called 
for any Data Type Address 


Address Data Type 
01A1 and Address1 


9999, 


QOKSCHD 


> 
———— ee 


QzmfChgMailMsg 


Change Mail Message 


Address2 |¢ 


Recipient Address and 
Address Data Type Changed 


Recipient List 


Figure C-3. Example of Preferred Address Resolution 
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Preferred Address 


Directory Search 


Data Type 01A5 
and Address2 


Directory 
Data 
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Appendix D. How Mail Server Framework Works with SNADS, Object 
Distribution, and OfficeVision 


This appendix describes how SNA distribution services has been organized differently. Applications that use 
(SNADS), as shipped by IBM, uses the mail server frame- SNADS, such as OfficeVision and Object Distribution, are not 
work (MSF) to route and distribute messages asynchro- affected by this change to SNADS. Figure D-1 on page D-2 


nously. The function of SNADS has not changed because of shows the current organization of SNADS. 
the introduction of the MSF. The SNADS routing function 


© Copyright IBM Corp. 1997 D-1 


AS/400 Mail Server 


o > 


> Create Mail Message l¢ 


ee Object Distribution 
Applications PENNS 
SNDNETxxx/ 
SNDDST/RCYDST ROVNETxx 
* ¥ t 
Distribution List |) Office Distribute OfficeVision || OPIECt 
Expansion ——, Function Receive Receive 
v * a 
SNADS Distribute SNADS Receive 
Function Function 
LF La 


—— 


Function 


TL 


List Expansion 


List Expansion 


p SNADS List 


! 


Address Resolution 


Address Resolution 


! 


Local Delivery 


Local Delivery 


——» Local Delivery 


‘ 


' 


Message Forwarding 


>> Forwarding 


A 
2 
2 
weenie 2 
‘ 
2 


Figure D-1. SNADS Overview 


Expansion Function 


p, SNADS Routing ¢—_}- > 


Function 


SNADS 


Function 


SNADS Message 


Function 


SNADS Reporting 


System 
Distribution 
Directory 
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ae Non-Delivery /-— >) Function 
SNADS FSO ; 
ere re Mepage nent Attachment Management |——® Management ae 
| Function 
F . SNADS 
Accounting . SNADS Logging 
Accounting -——> Function >} Journal 
SNADS Queuing 
Function i 
SNADS Distribution Queues 
A oe a pag eas iy sous 
SNADS SNADS SNADS SNADS 
SNADS Inbound Outbound Outbound Outbound 
Gateway Gateway Gateway Gateway | 
Function Vv 
X.400 VM/MVS SMTP 
| a. 8 
Vv Vv Vv | RV3W159-4 


The routing function of SNADS occurs within the exit point 

programs that are configured for the mail server framework 
exit points. Only seven of the ten available exit points are 

used by SNADS. 


e List expansion 

e Address resolution 

¢ Local delivery 

e¢ Message forwarding 

e¢ Non-delivery 

e Attachment management 
e Accounting 


List Expansion 


The SNADS exit program for list expansion expands a distri- 
bution list into a recipient list containing SNADS recipients. 
This exit program accepts the following address type: 


Type 
ATDDLIST 


Description 
Distribution list 


Address Resolution 


In the exit point program for address resolution, SNADS 
accesses the system distribution directory, the SNADS 
routing table, the SNADS distribution queues table, and the 
SNADS secondary system name table to determine the 
correct route of a message recipient. This exit program 
accepts the following address types: 


Type Description 

ATDGNDEN  Address/User ID 

ATRGEDGE System name/Address/User ID (fully qualified 
recipient name) 

ATRGNREN' Group name/System name 

ATDDLIST _ Distribution list 


Information that is stored in the system distribution directory 
(for example, preferred address and mail service level) can 
be used in determining the message type of a recipient. Pre- 
ferred address is generally used to determine the address 
type of a remote recipient (for example, TCP/IP or X.400). 
Mail service level is used to decide how the message will be 
stored for a local recipient. If the address is stored in the 
system distribution directory, the directory search API 
(QOKSCHD) can be used to query information needed by 
the user. 


If a recipient is local, the SNADS address resolution exit 
program checks the system directory to see what the mail 
service level is for that recipient. If the mail service level is 
user index, this exit program continues to process the recip- 
ient. If the mail service level is system message store or 
other mail service, this exit program does not route the recip- 
ient, and lets another address resolution exit program 
process it. 


If a recipient is remote, the SNADS address resolution exit 
program checks the system directory to see what address 


preference is stored for the recipient. If the preference is 
either the ATDGNDEN or the ATRGEDGE address type, 
then this exit program continues to route the recipient. If the 
preference is any other address type, this exit program does 
not route the recipient, and lets another address resolution 
exit program process it. 


After determining the correct route for a recipient, the 
SNADS address resolution exit program assigns a message 
type and status (local or remote) for that recipient. The 
SNADS message types include: 


Type Description 

MTDIA OfficeVision/400 type 

MTOBJDST = Object Distribution type 

MTDLS Document Library Services type 
MTDSNX Distributed System Node Executive type 


Local Delivery 


The SNADS exit program for local delivery routes a message 
to the local Object Distribution or OV/400 applications for all 
local recipients. This exit program accepts the following 
message types: 


Type Description 

MTDIA OfficeVision/400 type 

MTOBJDST Object Distribution type 

MTDLS Document Library Services type 
MTDSNX Distributed System Node Executive type 


Message Forwarding 


The SNADS exit program for message forwarding routes a 
message to the appropriate SNADS distribution queue for all 
remote recipients. This exit program accepts the following 
message types: 


Type Description 

MTDIA OfficeVision/400 type 

MTOBJDST = Object Distribution type 

MTDLS Document Library Services type 
MTDSNX Distributed System Node Executive type 
Non-Delivery 


The SNADS exit program for non-delivery creates a status 
message for those recipients who had routing or delivery 
errors. This exit program then uses the Create Mail 
Message API to put the new status message into the mail 
server framework to be routed. This exit program accepts 
the following message types: 


Type Description 

MTDIA OfficeVision/400 type 

MTOBJDST = Object Distribution type 

MTDLS Document Library Services type 
MTDSNX Distributed System Node Executive type 
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Attachment Management 


The SNADS exit program for attachment management 
manages the SNADS file server object attached to the 
message, if there is one. File server objects include files, 
spool files, or network jobs sent by object distribution, or doc- 
uments or notes sent by OV/400. This exit program accepts 
the following message types: 


Type Description 

MTDIA OfficeVision/400 type 

MTOBJDST = Object Distribution type 

MTDLS Document Library Services type 
MTDSNX Distributed System Node Executive type 
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Accounting 


The SNADS exit program for accounting makes entries in the 
QSNADS journal for any messages that are processed. The 
function types or entry types that can be journaled by this 
exit program include the following: 


*RTR/*NRM 
*RTR/*ERR 


The Display Distribution Log (DSPDSTLOG) command can 
be used to view the SNADS journal entries. See the SNA 
Distribution Services book for more information on SNADS 
journaling. 
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